Description of Changes

Adds a Kotlin Multiplatform client SDK for SpacetimeDB with full code generation support, gradle plugin to auto generate bindings, templates, docs, (ai agent) skills and smoketests.

Note: There is an existing PR for a Kotlin SDK (#4472 by @AndroidPoet). We developed independently. That PR provides a SDK without codegen, using raw byte data. So users have to manually encode/decode BSATN bytes and use string-based reducer names. This PR includes: Rust codegen generating typed table handles, reducers, and procedures, a Gradle plugin that auto-generates bindings on build, two project templates, and smoketests.

Rust cli:

• ktfmt formatting integration
• Language::Kotlin variant with aliases kt, KT
• ClientLanguage::Kotlin for template discovery
• binary file support for template generation (needed for gradle-wrapper.jar)
• 4 smoketests (unit tests, build validation, server integration)
• template smoketests covering basic-kt and compose-kt

Codegen (Rust):

• Typed data classes with BSATN encode/decode for all schema types
• Sealed interfaces for sum types, enum classes for plain enums
• Typed table handles with count/all/iter, callbacks, and index properties
• Typed reducer stubs with per-reducer event callbacks
• Typed procedure stubs with SdkResult<ReturnType, ProcedureError> results
• Module.kt entry point with extension properties (conn.db, conn.reducers, conn.procedures)
• Type-safe query builder with WHERE predicates, comparisons (eq/neq/lt/gt/lte/gte), and semi-joins
• subscribeToAllTables() and addQuery { qb -> qb.player().where { c -> c.health.gt(51) } }
• Kotlin keyword escaping (backticks), ByteArray equals/hashCode, variant name collision handling
• Snapshot tests, ktfmt formatting

SDK runtime:

• v2.bsatn protocol, Ktor WebSocket transport (user provides HttpClient)
• KMP: JVM, Android (API 27+), iOS (arm64, x64, simulator-arm64)
• DbConnection.Builder with: uri, databaseName, token, compression (Brotli/Gzip/None), lightMode, confirmedReads, callbackDispatcher
• EventContext hierarchy: SubscribeApplied, UnsubscribeApplied, Transaction, Reducer, Procedure, Error, UnknownTransaction
• TableCache<Row, Key> with persistent immutable collections (lock-free reads)
• UniqueIndex<Row, Col> (O(2) lookup) and BTreeIndex<Row, Col> (multi-value)
• 5-state subscriptions: PENDING, ACTIVE, UNSUBSCRIBING, ENDED
• Table callbacks: onInsert, onDelete, onUpdate (old+new), onBeforeDelete + remove variants
• One-off queries: suspend with timeout + callback variant
• SdkResult<T, E> with onSuccess/onFailure/map/getOrNull
• Typed errors: QueryError, ProcedureError, SubscriptionError
• Full type support: Identity, ConnectionId, Timestamp, TimeDuration, ScheduleAt, SpacetimeUuid (V5/V7), Int128/UInt128/Int256/UInt256, SpacetimeResult
• Stats/metrics: per-request latency tracking for reducers, procedures, subscriptions, one-off queries
• DbConnection.use { } resource management

Gradle plugin:

• generateSpacetimeBindings task (runs spacetimedb-cli generate --lang kotlin, wired to compileKotlin)
• generateSpacetimeConfig task (generates SpacetimeConfig.kt from spacetime.json)
• cleanSpacetimeModule task
• DSL: spacetimedb { cli.set(...); modulePath.set(...) }
• Hooks into both kotlin.jvm and kotlin.multiplatform plugins
• Graceful fallback if CLI not found

Templates:

• basic-kt: minimal CLI client with a Rust server module
• compose-kt: Compose Multiplatform chat app (Android + Desktop) with a full-featured Rust server module (users, messages, notes, scheduled reminders)

Example chat between android and desktop (jvm) using compose-kt template:

Jvm

Android

Benchmark:

Added Keynote-1 benchmark client (templates/keynote-2/spacetimedb-kotlin-client/): TPS benchmark matching the Rust client methodology.

Benchmark was run on: i7-12700H, 8GB Ram using 10 connections, 10s, alpha=1.5, confirmed reads

API and ABI breaking changes

CI now requires JDK 21+ installed in the smoketests job. The spacetimedb-new-runner-2 runner needs JDK 21+ available or the Kotlin tasks will fail.
No API or ABI breaking changes otherwise.

Expected complexity level and risk

2

The SDK and codegen are self-contained. The only touchpoints with existing code are:

• crates/codegen/src/lib.rs (3 lines: pub mod kotlin + re-export)
• crates/cli/src/subcommands/generate.rs (Kotlin variant in Language enum + dispatch)
• crates/cli/src/subcommands/init.rs (Kotlin variant in ClientLanguage enum)
• crates/cli/build.rs (binary file support for template embedding)
• crates/smoketests/ (new test files + Gradle lock helper)

No changes to existing SDK behavior or server-side code.

Testing

Note: sdk and templates are tested against Android and JVM (Linux). I do not have an iOS device so i could not test against native.

• cargo test -p spacetimedb-codegen (snapshot tests pass)
• cargo test -p spacetimedb-smoketests --test integration kotlin (unit tests, build validation, server integration)
• cargo test -p spacetimedb-smoketests --test integration test_all_templates (basic-kt and compose-kt)
• sdks/kotlin/ ./gradlew :spacetimedb-sdk:jvmTest
• sdks/kotlin/ ./gradlew :codegen-tests:test (generated bindings compile)
• Keynote-1 TPS benchmark against local server
• cargo fmt + clippy report no warnings
• Reviewer: spacetimedb-cli init --template basic-kt creates a working project
• Reviewer: spacetimedb-cli init --template compose-kt creates a working project

git clone https://github.com/FromWau/SpacetimeDB.git /tmp/spacetimedb-kotlin
cd /tmp/spacetimedb-kotlin
git checkout feat/kotlin-sdk
cargo build --release -p spacetimedb-cli -p spacetimedb-standalone

/tmp/spacetimedb-kotlin/target/release/spacetimedb-cli init \
    --template compose-kt \
    --project-path /tmp/compose-kt-test/ \
    --non-interactive \
    compose-kt-test

pluginManagement {
    repositories { /* ... */ }
    // Need to include the Gradle plugin locally because it's not yet published to Maven Central
    includeBuild("/tmp/spacetimedb-kotlin/sdks/kotlin/spacetimedb-gradle-plugin")
}

// Need to include the SDK locally because it's not yet published to Maven Central
includeBuild("/tmp/spacetimedb-kotlin/sdks/kotlin")

// Need to point to local CLI because it's not yet distributed via Maven Central
spacetimedb {
    cli.set(file("/tmp/spacetimedb-kotlin/target/release/spacetimedb-cli"))
}

kotlin {
    // ...
}

/tmp/spacetimedb-kotlin/target/release/spacetimedb-cli start

cd /tmp/compose-kt-test
/tmp/spacetimedb-kotlin/target/release/spacetimedb-cli publish \
    --server local --module-path spacetimedb -y compose-kt-test

cd /tmp/compose-kt-test
./gradlew :desktopApp:run

cd /tmp/compose-kt-test
./gradlew :androidApp:installDebug

Next steps

This PR needs the SDK and Gradle plugin published to Maven Central before merging. Right now templates and user projects require manually setting local SDK paths and plugin includes to work. Once published, they just pull dependencies from Maven/Gradle like normal. I'd publish under com.clockworklabs.spacetimedb-sdk and com.clockworklabs.spacetimedb-plugin. Would need access to the com.clockworklabs Maven namespace or a new one. If that works for you, I'll add a Kotlin publish workflow to CI.